Skip to content

Redesign the README and fix the library's Tailwind build - #4

Merged
operatoruplift merged 3 commits into
masterfrom
claude/readme-redesign
Oct 31, 2026
Merged

operatoruplift merged 3 commits into
masterfrom
claude/readme-redesign

Conversation

@operatoruplift

Copy link
Copy Markdown
Owner

What changed

The README described a published package used by three apps. The code says otherwise, and the library's own stylesheet was being compiled from the wrong Tailwind config. This rebuilds the README in the same house style as the pilot (allowance) and fixes the two build problems in separate commits.

  • Header: banner with a real Storybook capture, three buttons (run the Storybook, all 49 components, Operator Uplift today), stack badges, a one-line summary, the Build → Pack → Install → Import → Compose loop and section links.
  • Screens card: four real stories (ConversationThread, MemoryPanel, CommandPalette, Table), rendered for light and dark.
  • How it works: a Library → Package → Your app flow card and three properties checked against the code (tokens in CSS variables, server rendering, no keys and no network).
  • Status: SUPERSEDED for the library, ARCHIVED for the Uplift Assistant Electron app whose source is still in src/.
  • Where it fit: the platform this repo belonged to (webview, developer_console, core, calendar_agent, x402-agent, project_space, uplift-ai-chatbot), described the same way across this redesign.
  • Run it locally: Storybook, the checks, and a verified way to use the package without npm.
  • Tokens, hooks, the memory system, the repository layout and the component tables move into collapsible sections. No operational instruction was dropped.

Corrections to the old README

  • npm install @operatoruplift/ui cannot work: the package was never published (npm view @operatoruplift/ui returns E404). Replaced with build, npm pack, install the tarball, which I checked in a scratch app.
  • "Used By" listed the website, the developer console and the desktop app. None of them lists the package as a dependency, and the desktop shell loads the website rather than React components. The README now says it was meant to be shared and never was.
  • Counts: 49 components (not 47) and 17 exported hooks (not 13).
  • The memory example destructured entries, addMemory and searchMemories, which useMemory does not return. The new example uses index, save, search and remove, and type-checks.
  • "Next.js (SSR) and Tauri (CSR)" compatibility is rescoped to what was checked: 40 of 49 components carry "use client", and a packed build renders through react-dom/server.
  • The security note is kept in a narrower, checked form: library code reads no environment variables and makes no network requests.

Fixes

  1. Tailwind config (postcss.config.js, package.json): Tailwind 3 looks for tailwind.config.js before tailwind.config.ts, and the .js file belongs to the old Electron app. So dist/styles.css and Storybook compiled bg-primary to var(--primary), which the library never defines, and never generated bg-card: primary and danger buttons had no fill and cards had no surface. Both now name tailwind.config.ts. dist/index.js, index.cjs and index.d.ts are byte-identical before and after; only the CSS changes.
  2. Typecheck scope (tsconfig.json): npm run lint failed with 126 errors, every one in the old app's files (react-router-dom, zustand, electron and others left package.json in April 2026). Those 163 files are now excluded, with a comment. As a side effect the declaration build stops emitting .d.ts files for code the package does not contain.

Checks

Run on 30 October 2026 with Node 22.22.0 and npm 10.9.4:

  • npm ci: 445 packages installed.
  • npm run lint: 126 errors before (all outside the library), exit 0 after.
  • npm test: 26 files, 119 of 119 tests pass, before and after.
  • npm run build: passes. After the fix, dist/styles.css contains .bg-primary{background-color:var(--ou-primary)} and .bg-card{background-color:var(--ou-card)}.
  • npx storybook build: builds all 168 stories. Before and after captures of the Button story confirm the primary and danger colors were missing and are now back.
  • Consumer check: npm pack, then install into a scratch app with React 18. ESM and CommonJS imports work, styles.css and the preset resolve, a Button renders with react-dom/server, the README's three code samples pass tsc with skipLibCheck off, and Tailwind with the preset emits the token classes.
  • README check (check.mjs): no errors. Preview reviewed in light and dark.

Not fixed

  • 26 class uses with opacity modifiers on token colors (bg-primary/20, ring-primary/50 and similar) still generate no CSS, because the tokens are plain var() colors without <alpha-value>. This happened with both configs. Fixing it changes the token format, so it is left for you; the README documents it.
  • The old Electron app's 163 source files stay in src/. Deleting them is your call.
  • CLAUDE.md says Tailwind CSS 4; the library uses Tailwind 3.4.

Suggested repository settings

These live outside the code, so they are not in this PR:

  • Description (currently empty): "React components and design tokens from Operator Uplift's AI-assistant era. 49 components, 17 hooks, Storybook. Superseded."
  • Topics: react, component-library, storybook, tailwindcss, design-tokens, typescript
  • Social preview: upload docs/readme/banner.png (2400 × 1200) under Settings → General → Social preview.
  • Consider archiving the repository once this merges, since the library is superseded.

Generated by Claude Code

- tailwind.config.js (left over from the old Electron app) won Tailwind's
  lookup order, so dist/styles.css and Storybook compiled bg-primary to an
  undefined var(--primary) and never generated bg-card
- Point the CLI (-c) and the PostCSS plugin at tailwind.config.ts, which
  maps every token to the library's --ou-* variables
- index.js, index.cjs and index.d.ts are byte-identical; only the CSS changes

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5
- npm run lint failed with 126 errors, all in Uplift Assistant files whose
  dependencies left package.json in April 2026; none in the library
- Exclude those paths in tsconfig.json with a comment saying why
- npm run lint now exits 0, and the declaration build no longer emits stray
  .d.ts files for components/ui, components/auth, lib/supabase and lib/timeout

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5
- Banner, Storybook walkthrough and build flow cards in docs/readme/
- Mark the library superseded and the old Electron app archived, with the
  platform it belonged to
- Correct claims the code contradicts: the package is not on npm, no app
  imported it, 49 components and 17 hooks (not 47 and 13), and the
  useMemory example used return values that do not exist
- Replace the npm install step with a verified build, pack and install path
- Move tokens, hooks, memory, layout and the component tables into
  collapsible sections

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5
@operatoruplift
operatoruplift merged commit beb706d into master Oct 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants